BBS in a Box 4

home *** CD-ROM | disk | FTP | other *** search

/ BBS in a Box 4 / BBS in a Box - Macintosh - Volume IV (January 1992) (BBS in a Box).iso / Files / Prog / M / MCASSEMDOC < prev next >

Wrap

Text File | 1987-04-04 | 57.3 KB | 1,519 lines | [TEXT/MACA]

************************************************************************** McAssembly™ V6.5 Shareware Docs Copyright © 1986,87 By Signature Software ************************************************************************** (This document is layed out for Monaco 9, with tabs set to eight spaces.) ************************************************************************** CHANGES IN VERSION 6.5 ************************************************************************** * BASE can now be used with no symbol operands to specify a base register for all subsequent labels. ENDB is used to turn off such basing. * DSEC can now have an optional address register operand which causes all labels in the dsec to be based to the specified register. * DEND can now have an optional symbol operand which will be set to the size of the dsec. (Similar to the same capabilities on the ENDP and ENDL pseudo-ops.) ************************************************************************** CHANGES IN VERSION 6.4 ************************************************************************** * User-definable linker .MAP file formats may now be created - see the section on user-definable maps for details. * Fixed a bug which sometimes caused a hang when the output window was resized. * Added the IFLIST pseudo-op to the assembler which allows unassembled conditional assembly clauses to be listing suppressed. * Fixed a bug in the assembler - MOVEQ with an operand in the range of +128...+255 will now cause an error. * Fixed a bug in the assembler - operands of the form exp8(Dn) where exp8 is in the range [+128...+255] or [-129...-256] will now cause an error. * Fixed a bug in the linker - word offsets in the range [+32768...+65535] or [-32769...-65536] are now reported as errors. * In the linker, if an error occurs, the program counter where the error occurred is shown in the error message where applicable. * McAssembly now obtains the creator signatures for all TEXT files that it creates from a STR,128 resource. * A printer initialization string may now be stored in a STR,129 resource. ************************************************************************** CHANGES IN VERSION 6.3 ************************************************************************** * Added the DEFALL pseudo-op to the assembler. * Added the ERROR pseudo-op to the assembler. * Fixed a bug in the assembler - MOVEM instructions with PC-relative operands now assemble correctly. ************************************************************************** CHANGES IN VERSION 6.2 ************************************************************************** * Single quotes are now allowed as string delimiters. * Macro parameters can now be picked off as substrings by &n[start:length]. * New string escape codes: /', /D, /S, /U, /A. * New pseudo-op DEFINE allows the use of string variables for string replacements in the source line before assembly. * << and >> are now accepted for SHL and SHR. * ALIGN now accepts an operand and may be coded as .ALIGN. * New pseudo-ops INCLUDE, OPWORD, and ENDIF are the same as INCL, TRAPW, and ENDI, respectively. * Assembly error lines may now be copied to the clipboard. ************************************************************************** INTRODUCTION ************************************************************************** This document briefly describes the McAssembly program - an assembler, resource compiler, linker, and job controller for the Macintosh. McAssembly is a shareware program - if you like it and use it, then please register it by sending $40.00 to: Signature Software (checks payable to same) 2151 Brown Ave. Bensalem, PA 19020 (215) 639-8764 All registered owners will receive the following: • a 94-page manual • the latest version of the program • Apple's EDIT editor • a symbolic debugger called McBug • several example working applications source code files • all of the standard Apple equate, trap, and .rel files in McAssembly format • a utility to convert McAssembly .rel files to MDS .rel files • 24-hour, 7-day telephone support (Supplied on an 800K HFS diskette unless otherwise requested.) I strongly recommend that you register it if you use it, just for the additional examples and manual alone. (This document must of necessity be very brief - the manual goes into much greater detail. The MacWrite manual files are over 200K, which I thought was too much to expect people to download, so I've condensed them into this text file.) To those of you who might object that this isn't a complete package because I've not distributed everything that you should have (particularly the system equate files and examples), I answer as follows: • The whole package takes up almost 800K of disk space - I can't imagine anyone seriously wanting to download that! The $40.00 registration fee is probably a wash when you consider the download charges, the time to download and print the docs, and the aggravation. The documentation presented here, while condensed, does represent all of the essential information that you need to know to use the program, it's just a lot easier if you have the whole package. In addition, don't forget that the whole package is a complete assembly language development system. Something as complex as that hardly lends itself to electronic distribution. In fact, I think I've done a masterful job just in getting all of the information you need to use it in only this 50K file. • Parts of the package are copyright by Apple Computer, and I can't distribute them indiscriminately. I can supply them to registerees under the terms of my license with Apple. • If you're an experienced Mac assembly language programmer, then the information presented here is probably more than enough to get you going. If you're converting from some other assembler to McAssembly, you may not even need the whole package (although I would still expect you to register.) If you're an inexperienced Mac programmer, then the examples in the registered package, the system files, and my telephone support would probably be of value to you, but I don't see how anyone could object to paying for those. • Given the current registration ratios of other Macintosh shareware programs, what's wrong with having a little incentive to register? ____________________________________ | | | Dave McWherter 12/01/86 | | | | Compuserve 70057,1612 | | Delphi DMcWherter | | Genie D.McWherter | |__________________________________| ************************************************************************** THE MENU SELECTIONS ************************************************************************** First, a description of the menu options: File menu: Assemble assembles a file Link links a group of files Run job executes a .job file Save options save current McAssembly options Quit what else? Assembler menu: Object file creates a .rel object file Listing to printer echoes output to printer Listing to screen echoes output to screen Listing to file echoes output to .lst file Errors only listing only outputs error lines Symbol table outputs symbol table at end Cross reference outputs cross reference table at end Terse cref mode removes unref'ed .PSM symbols from cross reference list .PSM file creates a .PSM file DEF all symbols DEFs all non-.PSM symbols in the file No listing headers suppresses headers in listings MPW object format object file will be in MPW format, .o Error lines to clip copies error lines to clipboard Linker menu: Symbol table outputs symbol table at end .MAP file output echoes output to .map file Printer output echoes output to printer McBug .SYM file creates symbol file for use with McBug Raw code data file puts output code in data fork of file with no resource formatting User .MAP file creates a .map file in a user-defined format Jobs menu: Stop if Asm error stop the job if assembly error occurs No link if Asm error don't link if assembly error occurs Force assemblies force all files in job to be assembled Misc. menu: Enable Beep enable beep at end of commands Use .Print driver route printer output through the driver (else goes directly to serial port B) Transfer menu: EDIT to EDIT program QUED to QUED program MDS Convert to MDS Convert program Other to any other program ************************************************************************** SOURCE LINE FORMAT ************************************************************************** All source code lines must be in the following form: [label] opcode [operand] [;] [comment] Tabs or spaces separate fields, and >>> only one tab (or space) can appear between the opcode field and the operand field <<<. Labels may contain up to 100 characters, all of which are significant. Labels may contain alphanumeric characters and any of the following characters: _, %, !, @, #, $, ?, or period. Labels may be suffixed with a colon if desired. The semicolon comment designator character is optional in the majority of cases. Specifically, if an opcode appears in the line then you can omit the semicolon. If a line contains just a label and a comment, then you have to use the semicolon. ************************************************************************** ARITHMETIC EXPRESSIONS ************************************************************************** All arithmetic and logical operations are 32-bit operations. McAssembly supports the following operators and special characters. + integer addition - integer subtraction / integer division (32 bits/32 bits = 32 bits) * integer multiplication (32 bits * 32 bits = 32 bits) MOD integer modulus SHL logical shift left (16 SHL 2 = 64) << same as SHL SHR logical shift right (16 SHR 3 = 2) >> same as SHR AND logical bit AND OR logical bit OR XOR logical bit eXclusive-OR NOT logical bit inverse 'xxxx' character constant (1-4 characters, right justified) * current value of program counter $ specifies a hexadecimal number % specifies a binary number (The following relational operators return true or false; true = $FFFFFFFF and false = 0.) <= less than or equal <> not equal >= greater than or equal < less than > greater than = equal to The expression processor uses standard algebraic precedence rules. Use parentheses to force precedence. ************************************************************************** ALIGNMENT ************************************************************************** McAssembly automatically aligns those things that must be on an even address (opcodes, variable or constant words and longs, trap words, etc.) by putting a zero byte in front of them if necessary. However, labels on automatically aligned lines still carry the value of the address before the alignment. These may be odd. If this happens, McAssembly warns you with a LABEL ON ODD ADDRESS message. If that's what you really wanted, then you can ignore the warning. Otherwise, you must change the code accordingly, probably by adding an explicit ALIGN pseudo-op, and reassemble. ************************************************************************** THE ASSEMBLER PSEUDO-OPS ************************************************************************** (These are almost in alphabetical order. In some cases, pseudo-ops which are used together are grouped together for description purposes.) A5OFF <absolute expr> specify initial A5 offset A5SEC define A5 offset variables A5END end an A5SEC A5REF <symbol> [, <symbol>, ...] reference an A5SEC variable All global data which is to be stored offset from A5 must be defined between A5SEC and A5END. You can have as many A5SEC's in a file as you want - the linker concatenates them. A5OFF may be used to specify the initial offset below A5 for all of your globals, and defaults to $100. A5REF is used to reference A5 variables which are defined in other modules. Symbols which are defined as A5 variables don't have to have the '(A5)' suffixed to them. For example: a5off grafSize a5sec global1 ds.l 1 global2 ds.w 2 a5end a5ref external move global1,d0 this is the same as... move global1(a5),d0 this move external,d0 and this is the same as... move external(a5),d0 this ALIGN [<expr>] aligns the PC to a multiple of <expr>, default = 2 .ALIGN [<expr>] aligns the PC to a multiple of <expr>, default = 2 BASE An, <symbol> [,<symbol>, ...] auto-offsets specified symbols by An BASE specifies that a symbol is to be offset by the specified address register every time you use it For example, if you do this: base a6,sym1,sym2 move sym1,d0 then this instruction move sym1(a6),d0 is the same as this one and move sym1(a3),d0 you can override it if you want BASE An auto-offset all subsequently defined symbols by An ENDB turn off symbol basing (only necessary if no symbols are specified in the BASE operand list) CASE turns on case sensitivity If you don't use CASE, then case in labels is not significant. DB <expr> [, <expr>, ...] define constant bytes at the PC DC <expr> [, <expr>, ...] define constant words at the PC DC.B <expr> [, <expr>, ...] define constant bytes at the PC DC.L <expr> [, <expr>, ...] define constant longs at the PC DC.W <expr> [, <expr>, ...] define constant words at the PC DL <expr> [, <expr>, ...] define constant longs at the PC DW <expr> [, <expr>, ...] define constant words at the PC DCB <count>, <value> define block of <count> bytes of <value> DCB.B <count>, <value> define block of <count> bytes of <value> DCB.L <count>, <value> define block of <count> longs of <value> DCB.W <count>, <value> define block of <count> words of <value> FILL <count>, <value> equivalent to DCB DEF <symbol> [, <symbol>, ...] externally define symbols XDEF <symbol> [, <symbol>, ...] externally define symbols DEF and XDEF are equivalent - they allow symbols in this file to be referenced from another file. DEFALL Same as DEF'ing every symbol in the file. DEFINE "string" define a string symbol; the symbol may then be used anywhere in a source line between curly brackets and will cause a string replacement before the line is assembled. For example: hello define "goodbye" if you define hello to be 'goodbye' text "* {hello} *" then this string will be '* goodbye *' DSEC <absolute expr> [<An] start dummy section, org'ed at <absolute expr>, base all labels inside to An DSEC [<symbol>] end a DSEC, symbol is set to size of the DSEC RSEC [An] begin reverse DSEC, org'ed at 0, and BASE symbols inside to An (default A6) ENDR [<symbol>] end an RSEC, symbol set to size of the section DSEC and DEND delimit "dummy sections", which may contain only storage allocation statements. No storage is actually allocated for items in a dummy section - their primary use is to assign values to record structures. Only storage allocation statements are allowed in dummy sections. For example: dsec 1 sym1 ds.b 1 will have a value of 1 sym2 ds.w 1 will have a value of 2 sym3 ds.l 1 will have a value of 4 dend Dummy sections may also be defined in 'reverse' using RSEC, for example: rsec sym1 ds 0 will have a value of 0 sym2 ds.w 1 will have a value of -2 sym3 ds.l 1 will have a value of -6 sym4 ds.w 1 will have a value of -8 endr rsize rsize will have a value of 8 DS <count> define <count> words of storage at PC DS.B <count> define <count> bytes of storage at PC DS.L <count> define <count> longs of storage at PC DS.W <count> define <count> words of storage at PC BOOLEAN <count> same as ds.w (These allow more mnemonic DS's...) BYTE <count> same as ds.b " " " " CHAR <count> same as ds.w " " " " HANDLE <count> same as ds.l " " " " HDL <count> same as ds.l " " " " INTEGER <count> same as ds.w " " " " LONG <count> same as ds.l " " " " LONGINT <count> same as ds.l " " " " POINT <count> same as ds.l " " " " POINTER <count> same as ds.l " " " " PTR <count> same as ds.l " " " " RECT <count> same as ds.b 8*<count> VAR <count> same as ds.l " " " " WORD <count> same as ds.w " " " " IF <absolute expr> conditional assembly ELSE used with IF ENDI end an IF clause ENDIF end an IF clause IFDEF <symbol> true if symbol defined IFNDEF <symbol> true if symbol undefined IF1 true if pass 1 IF2 true if pass 2 Conditional assembly control. For example: if 0 the expr is not true, so <statements> these statements aren't assembled else (else clauses are optional) <statements> but these statements are endi IFLIST <expr> conditional listing control If the expression is true (the default condition), then conditional assembly clauses which aren't assembled will appear in the listing, otherwise they won't. END end of program (optional) EQU <expr> equate symbol to <expr> EQU.B <expr> equate symbol to <expr> (equivalent to equ) EQU.W <expr> equate symbol to <expr> (equivalent to equ) EQU.L <expr> equate symbol to <expr> (equivalent to equ) ERROR "your error message" Allows user-definable assembly errors. FSIGN <absolute expr> specify program's Finder file signature FTYPE <absolute expr> specify program's Finder file type For example, if you're assembling an application, then: ftype 'APPL' fsign 'ursg' Or, if you're assembling a desk accessory to be installed by the Font/DA Mover: ftype 'DFIL' fsign 'DMOV' IPATH "pathname" specify an HFS path to subsequent include files INCL "filename" include another source file INCLUDE "filename" include another source file JTBL <symbol> [, <symbol>, ...] specify jump table entries Any symbol that's referenced from another segment by a Bcc, DBcc, JSR, JMP, LEA, or PEA instruction >>> must <<< be specified as a jump table entry. LINE [ <char> [ , <count> ] ] prettyprint a line of chars Outputs a listing line filled with the specified number of characters. <count> defaults to 50, and <char> defaults to '*'. LIST <absolute expr> listing control If the expression is true (not 0), then subsequent source lines appear in the listing, otherwise they won't. LFRAME [An] begin local variable stack frame, and BASE symbols inside to An (default A6) ENDL [<symbol>] end a LFRAME, symbol is set to size of the frame LFRAME and ENDL allow local variables which are to be stored on the stack to be easily defined. Symbols defined within the frame are automatically BASE'd to the specified register so that you don't have to suffix them with '(An)'. For example: lframe local1 integer will have an a6 offset of -2 local2 longint will have an a6 offset of -6 local3 rect will have an a6 offset of -14 endl lsize will have a value of 14 Subroutine_Entry link a6,#-lsize save stack space for locals move local1,d0 this instruction is the same as... move -2(a6),d0 this one ... unlk a6 clear locals from stack rts return LOC start new local scope block LOCSYM <expr> change local label character NOLOC auto-LOC on non-local labels Local symbols begin with a period and may contain the same cast of characters as normal labels. Their scope normally extends from one LOC statement to the next LOC statement. This can be changed with the NOLOC statement, which causes local symbol scopes to extend from one non-local label to the next non-local label. The local symbol prefix character can be changed with the LOCSYM statement. For example, loc .hello nop this .hello loc .hello nop is different than this .hello .hello nop but this .hello causes an error Or, using NOLOC, and LOCSYM (for MDS compatibility): noloc locsym '@' goodbye nop @hello nop this @hello solong nop @hello nop is different than this @hello @hello nop but this @hello causes an error MACRO [&1,&2,...,&F] begin a macro definition MACROX [&1,&2,...,&F] ditto, no auto LOC on call ENDM end a macro definition MEXP <absolute expr> macro expansion control These control macros. For example, given a macro called test defined as: test macro &1,&2,&3,&4,&5,&6 move &1,d0 lea &2,a0 if &&3 = "hello" nop endi text &&4 notice quote enclosure lab%5 nop notice expand as value string &6 parameters may be opcodes text "&2[2:3] param substring [start:length] endm And a call to test like this: num equ 1234 test d2,symbol,hello,mikey,num,_Open Then it would be expanded to the following: move d2,d0 lea symbol,a0 nop text "mikey" lab1234 nop _Open text "ymb" MACROs do an automatic LOC on entry so that local symbols inside the macro have their own scope. This prevents local symbols inside the macro from conflicting with local symbols outside it. MACROX's do not do the LOC - so that you can pass local symbols to a macro if you want. MEXP controls whether or not macro expansions appear in the listing: they will appear if the expression is true. NAME <symbol> specifies the module name (one source file is a module) PAGE ["title"] page eject, optionally specifying a page title PFRAME [An] begin parameter stack frame, and BASE symbols inside to An (default A6) ENDP [<symbol>] end a PFRAME, symbol is set to size of the frame PFRAME and ENDP allow parameters passed on the stack to subroutines to be easily defined. For example, suppose you have a subroutine whose Pascal definition is: FUNCTION Slush (parm1: LONGINT; parm2: INTEGER; parm3: BOOLEAN) : INTEGER; Then you could code it in McAssembly as follows: pframe result integer will have an a6 offset of 16 parm1 longint will have an a6 offset of 12 parm2 integer will have an a6 offset of 10 parm3 boolean will have an a6 offset of 8 endp psize will have a value of 10 Slush link a6,#0 move parm2,d0 then this is equivalent to move 10(a6),d0 to this ... move d0,result returns the result unlk a6 move.l (sp)+,a0 get return address addi.l #psize-2,sp clear parameters (leave result) jmp (a0) and return Notice that PFRAME automatically allocates space for a stacked return address and a stacked linkage register, so you have to do a 'link' instruction on entry to the routine if you use PFRAME. The ENDP is optional is you have an LFRAME immediately following. PRMT "prompt" display a prompt on the screen PRTR "string" send ctrl string to printer PSIZE <absolute expr> set listing page size REF <symbol> [, <symbol>, ...] reference external symbols XREF <symbol> [, <symbol>, ...] reference external symbols REF and XREF are equivalent and allow you to reference symbols which are defined in other modules. REQU Dn | An | <register symbol> equate symbol to a register For example: dataptr requ a4 move.l (dataptr),d0 then this is the same as... move.l (a4),d0 this bufptr equ dataptr move.l bufptr,d1 and this... move.l a4,d1 is the same as this RPATH "pathname" specify an HFS path for the .rel object file SET <expr> set symbol to value, may be reSET again STRING <expr> set DC.B string formats: 0 = no length byte prefixes (default) else prefix with length bytes TABS <n> specify listing tab stops every <n> columns TCOMP activate the trap compiler (described later) TERSE set short listing format (no line numbers, 16 bits of program counter) TEXP <absolute expr> text expansion control If the expression is 0, then only one line of object bytes appears in the listing for a TEXT statement. Otherwise all of the bytes generated by the text will appear in the listing. TEXT [ - | + | # ] "string" define a text string '-' sets bit 7 on the last byte of the string. '+' sets bit 7 in every string byte (Apple ][ forever!). '#' stuffs a length byte in front of the string. (Only one prefix is allowed at a time.) You can use the following escape characters in the string: /R carriage return $0D /L linefeed $0A /" double quote $22 /T tab $09 /E escape $1B /0 null $00 // slash $2F /F formfeed $0C /B backspace $08 /$hh any hex number $hh /' single quote $27 /D current date /S select short date form /U select unabbreviated long date form /A select abbreviated long date form (the default) For example: text #"ABC" generates 05 41 42 43 text +"ABC" generates C1 C2 C3 text -"ABC" generates 41 42 C3 text "ABC/T/$21/R" generates 41 42 43 09 21 0D TITLE "string [$] " specify listing page title, '$' generates a timestamp TRAPW <absolute expr> define a trap word OPWORD <absolute expr> define a trap word For example: _Open trapw $A003 _Open ************************************************************************** STRING DELIMITERS ************************************************************************** In all of the above pseudo-op descriptions, strings have been shown delimited by double quotes as in "string". However, you may also delimit them with single quotes as in 'string'. The only place you can't use single quotes as delimiters is in IF comparisons (because then the single quoted item would be evaluated as a character constant.) ************************************************************************** .PSM FILES ************************************************************************** Packed symbol files are binary files containing only symbol definitions. They're smaller in size than their text equivalents. This saves disk space and speeds up assembly. They also speed up assembly because they're read only on the first pass of the assembly. They're not read on the second pass. Packed symbol files have a filename suffix of .PSM. You can create a file of symbol definitions from any source file. Just select the assembler .PSM file option and assemble the file. McAssembly dumps all the names of all symbols defined in the file and their values to a .PSM file at the end of the assembly. You use .PSM files by INCLuding them in your source files. Symbols that are defined in more than one INCLuded .PSM file are not flagged as multiply defined symbols. The symbol takes the value of the last definition of it processed by McAssembly. This allows you to use .PSM files containing overlapping symbol definitions without worrying about multiple definitions. ************************************************************************** THE TRAP COMPILER ************************************************************************** McAssembly contains a built-in Trap Compiler which allows certain toolbox and O/S traps to be invoked with one line of source code. It eliminates much of the drudgery from trap setup and interfacing. For brevity, we'll call the Trap Compiler simply the TC throughout the rest of this section. The TC was designed to simplify interfacing to the Macintosh stack-based traps. Stack-based traps are those traps which pass parameters and return results on the 68000 stack. (As opposed to register-based traps, which pass parameters and return results in 68000 registers.) Interfacing to stack-based traps requires a standard sequence of steps which are common to all such traps: 1.) If the trap is a function, make room on the stack for the function result. 2.) Push the parameters on the stack. 3.) Execute the trap. 4.) If the trap is a function, remove the function result from the stack. This standard sequence requires a large amount of source code overhead each time a trap is called. Not only is this process tedious to code, but it is also prone to errors. The purpose of the TC is two-fold: to eliminate the coding overhead and to automate the sequence as much as possible in order to eliminate coding errors. The TC is not available for use unless you specifically invoke it by using the TCOMP pseudo-op. If you want to use the TC, just specify TCOMP at the beginning of your source file. TCOMP loads the symbol table with special highly encoded macrox definitions of all the stack-based traps. Once you've activated the TC with TCOMP, you can then invoke any stack-based trap by specifying the name of the trap as an opcode and follow it with a list of parameters as operands like this: TrapName <tab> param1, param2,...,paramn [,=result] Notice that TrapName is not preceded by an underscore character. This allows you to bypass the TC and manually invoke all of the traps by using the trap name preceded by an underscore. The list of parameters param1...paramn varies depending on the trap you're calling. The parameters in the list correspond exactly to the PASCAL definitions of the traps in Inside Macintosh. Some traps don't have any parameters, in which case you don't specify any. The contents of the parameters you specify are automatically pushed onto the stack for you by the TC. The size of the item pushed (byte, word, long) is also automatically taken care of for you by the TC. In some cases, you'll want to use the address of a symbol as a parameter instead of its contents. The TC allows you to do that by specifying an exclamation point character ! in front of the parameter. Note that ! is only allowed on parameters of size long. The =result item is only used on functions. If the trap returns a result on the stack, then it's a function and you have to specify where you want the result to be stored. In the case of functions, the TC automatically creates room on the stack for the function result before stacking any input parameters and pops the result off the stack after the trap returns and stores it in the result parameter you specify (again, taking care of sizing automatically.) The = before a result item is optional. It's only purpose is to improve readability of your code. All of this may sound complex, but it's really pretty easy to use. Examples are a better way to explain it, so... AN EXAMPLE Here's an example of using the TC. We'll use the Menu Manager trap _NewMenu which has a PASCAL definition of: function NewMenu (menuID:INTEGER; menuTitle:Str255) : MenuHandle Here's a code fragment using this trap: tcomp turn on the trap compiler ourTitle text #"Example" parameters we'll need ourMenu equ 100 a5sec MHandle ds.l 1 a5end NewMenu #ourMenu,!ourTitle,=MHandle This trap call would be expanded by the TC to the following sequence: subq.l #4,sp move.w #ourMenu,-(sp) pea ourTitle,-(sp) dc.w $A931 move.l (sp)+,MHandle Notice that in this example we needed the address of the title so we prefixed ourTitle with !. Let's use the same trap for another example. Assume that this time we have computed the value of the menu ID and the address of the title string dynamically. Assume further that the menu ID is in register D1 and the title string address is in A2. We would then invoke the trap as follows: NewMenu d1,a2,a0 Which would expand to: subq.l #4,sp move.w d1,-(sp) move.l a2,-(sp) dc.w $A931 move.l (sp)+,a0 Notice that this time we didn't specify the = to indicate a function result. This is perfectly acceptable but not as readable. Also notice that we stored the result in register A0 as opposed to MHandle. A NAMING QUIRK There are two stack-based traps which have the same names as McAssembly opcodes: the QuickDraw traps Move and Line. To avoid conflicts, if you want to use the TC on these traps, be aware that they're renamed QDMove and QDLine in the TC. You have to use these new names if you want the TC to recognize these two traps. WHAT TRAPS AREN'T RECOGNIZED The trap compiler doesn't contain definitions for the following traps (because they're register-based): Device Manager File Manager Memory Manager OS Event Manager OS Utilities Segment Loader In addition, only the following packages are supported: International Standard File Disk Initialization SCSI Manager List Manager (The trap compiler contains definitions for all of the stack-based Mac+ traps for the new 128K ROM.) USING IT WITH .PSM FILES There are naming conflicts between the names recognized by the TC and some equates in the .PSM files. In particular, some "routine selector" equates will cause conflicts. For example, SFGetFile is both a legal TC trap name and a routine selector equate in the PackMacs.PSM file. If you want to use the TC with the .PSM files, then you must activate it after you've included the .PSM files!. In other words, don't use TCOMP until after all of your includes. If you do this, then the symbols which are in both files will be forced to be trap compiler names. The duplicated symbols will no longer be available as equated values. Which is what you want, since if you're using the TC, then you won't need the routine selector equates. ************************************************************************** THE RESOURCE COMPILER ************************************************************************** McAssembly contains a built-in Resource Compiler which can assemble resource definitions. A two-character resource delimiter at the start of a source line identifies resource definitions. The delimiter sequence $$ starts a standard resource definition, a definition of a resource type that McAssembly knows how to interpret. The delimiter sequence [[ starts a user-defined resource definition, a definition of a resource type that McAssembly doesn't know how to interpret. The delimiter sequence ]] ends a user defined resource definition. Standard resource definitions don't require an ending delimiter because McAssembly knows where the resource definition ends from information you supply in the definition. The formats of the two types of definitions are as follows: $$ TYPE, ID, ATTR, NAME [<tab>] [;] [comment] <item list> or [[ TYPE, ID, ATTR, NAME [<tab>] [;] [comment] <code and/or data> ]] TYPE is a four-character resource type. For standard definitions, it must be one that McAssembly recognizes. For a user-defined definition, it can be any four characters. ID is the resource ID number. ATTR specifies the attribute byte for the resource. NAME is the name string of the resource. ATTR and NAME are optional parameters and may be omitted, although you can't omit the ATTR if you want to specify a NAME. Here are two examples for a standard resource, one with all parameters specified, and one with ATTR and NAME omitted: $$ ALRT, 2, 0, alert no. 2 $$ WIND, 1 The item list is simply a list of items that make up the resource definition. McAssembly interprets each item in the list in a certain way. The types of items you specify in the list must correspond exactly with the types of items that McAssembly expects for that resource. If you specify an item of the wrong type or if you specify too many or too few items, you'll get syntax errors (many) on subsequent lines of the file. Items in the item list appear at the beginning of subsequent source lines after the line containing the $$. The format of lines in the item list is as follows: item [, item, ...] [<tab>] [;] [comment] item [, item, ...] [<tab>] [;] [comment] etc... for as many lines as it takes to specify all items As you can see, you have your choice of entering each item on its own source line, or of placing several items on one line, or a combination of either. McAssembly ignores all subsequent characters on the line after a tab or ; character and skips to the start of the next line for the next item in the list. There are several types of items. The type of each is marked in the descriptions of the formats for each standard resource. These types have the following meanings: bexp an expression interpreted as a byte wexp an expression interpreted as a word lexp an expression interpreted as a long chrl a four-character long str a string bexp, wexp, and lexp items are numeric expressions and can be any legal McAssembly expression. In most cases, you don't have to worry about what size the expression is. In some cases you do, particularly in the bit maps, which McAssembly interprets as a sequence of longwords. Enter chrl items as a sequence of from one to four characters. If you specify fewer than four characters, then the item is left justified in a 32-bit long and padded on the right with spaces. Don't enclose the characters in quotation marks. You may enter strings in either of two ways. First, if your string contains no special characters or leading spaces you can just type the string. If it does contain special characters or leading spaces, you must enclose the string in quotation marks as "string". (Any of the escape sequences allowed in TEXT strings are allowed in string.) If your string isn't enclosed in quotation marks, then you can continue the string to the start of the next line by ending the string with a \ character. Strings enclosed in quotes can't be continued to the next line. You can specify a null string (a string with a length of zero) with the vertical bar |. The code and/or data in a user-defined resource may be any combination of legal McAssembly instruction opcodes or pseudo-ops. The definition must end with the ]] delimiter or you'll get an error message. STANDARD RESOURCE FORMATS What follows is a list of the standard resource types that McAssembly recognizes and the formats of the item lists for each. Each item in these formats appears on its own source line but that doesn't have to be the case. They're only shown that way here for clarity. ---------------------------------------------------------------------------- $$ ALRT,ID,ATTR,NAME TOP wexp bounds rectangle: LEFT wexp BOTTOM wexp RIGHT wexp DITL_LIST_ID wexp resc ID of item list STAGES wexp see DLOG Mgr, IM, page 35 ---------------------------------------------------------------------------- $$ BNDL,ID,ATTR,NAME SIGNATURE chrl application's signature VERS_DATA_RESC_ID wexp 0 by convention NO_RESC_TYPES wexp no. of BNDL resc types that follow: For each resc type: RESOURCE_TYPE chrl typically ICN# or FREF NO_MAPPINGS_THIS_TYPE wexp no. of mappings that follow: For each mapping: LOCAL_ID wexp ACTUAL_ID wexp ** Note: If you use the standard BNDL resource in a module, then McAssembly automatically sets the bundle bit in the output file after the link is completed. ---------------------------------------------------------------------------- $$ CNTL,ID,ATTR,NAME TOP wexp bounds rectangle: LEFT wexp BOTTOM wexp RIGHT wexp INITIAL_VALUE wexp current value of control VISIBLE wexp boolean MAX_VALUE wexp maximum value of control MIN_VALUE wexp minimum value of control CTRL_DEFINITION_ID wexp resc ID of the definition function for the control type: 0 simple button 1 check box 2 radio button 8 add to use window's font 16 scroll bar REFCON lexp user defined value TITLE str the control's title ---------------------------------------------------------------------------- $$ CURS,ID,ATTR,NAME CURSOR_DATA_BYTES lexp eight longs of cursor image: " lexp " lexp " lexp " lexp " lexp " lexp " lexp CURSOR_MASK_BYTES lexp eight longs of cursor mask: " lexp " lexp " lexp " lexp " lexp " lexp " lexp H_OF_HOT_SPOT wexp horizontal of the hot spot V_OF_HOT_SPOT wexp vertical of the hot spot ---------------------------------------------------------------------------- $$ DITL,ID,ATTR,NAME NO_ITEMS_IN_LIST wexp no. of items in this list: For each item in the list: HANDLE_HOLDER lexp placeholder for handle or pointer - normally 0 TOP wexp display rectangle (local coordinates): LEFT wexp BOTTOM wexp RIGHT wexp ITEM_TYPE bexp type of the item: 0 user defined (dialog only) 4 std button control 5 std check box control 6 std radio button control 7 defined in CTRL template 8 static text 16 editable text (dialog only) 32 icon 64 QuickDraw picture 128 add to any of above to disable ITEM ---- the actual item; contents of this field depend on item type as follows: If item type is, then content is: 4,5,6 str control title 7 wexp resc ID of template 8,16 str the text 32,64 wexp resc ID of ICON or PICT 0 nil empty (length = 0) ---------------------------------------------------------------------------- $$ DLOG,ID,ATTR,NAME TOP wexp bounds rectangle: LEFT wexp BOTTOM wexp RIGHT wexp WINDOW_DEFINITION_ID wexp the type of window: 0 std doc wind or modeless dialog box 1 alert box or modal dialog box 2 plain box 3 plain box with shadow 4 doc window without size box 16 rounded corner window VISIBLE wexp boolean, initial state of dialog GOAWAY wexp boolean, TRUE means window has a close box REFCON lexp user defined value RESC_ID_OF_ITEM_LIST wexp resc ID of the DITL for this dialog TITLE str the dialog's title (0 length string if modal dialog box) ---------------------------------------------------------------------------- $$ FREF,ID,ATTR,NAME FILETYPE chrl typically APPL LOCAL_ID_FOR_ICON_LIST wexp FILENAME str filename that should follow the file to a new disk (null string if none) ---------------------------------------------------------------------------- $$ ICON,ID,ATTR,NAME (32) ICON_BYTE_LONGS lexp icon bit map - 32 longs: ... ... ---------------------------------------------------------------------------- $$ ICN#,ID,ATTR,NAME (32) ICON1_BYTE_LONGS lexp icon bit map - 32 longs: ... ... (32) ICON2_BYTE_LONGS lexp icon bit map mask - 32 longs: ... ... ---------------------------------------------------------------------------- $$ MENU,ID,ATTR,NAME WIDTH_HOLDER wexp 0 - placeholder for menu width HEIGHT_HOLDER wexp 0 - placeholder for menu height STD_MENU_PROC_HOLDER lexp normally 0 ENABLE_MASK lexp bit 0 set if menu enabled, bit 1 set if menu item 1 enabled, bit 2 set if menu item 2 enabled, etc... MENU_TITLE str the menu's title NUMBER_MENU_ITEMS wexp number of items in the menu: For each menu item: MENU_ITEM str the text of the item ICON_NUMBER bexp 0 = none, ICON'S resc ID = ICON number + 256 KEYBD_EQUIV bexp equivalent kybd char code, 0 = none MARKING_CHAR bexp marking char code, 0 = no mark TEXT_STYLE bexp text style of the item: bit 0 = bold bit 1 = italic bit 2 = underline bit 3 = outline bit 4 = shadow bit 5 = condense bit 6 = extend ---------------------------------------------------------------------------- $$ PAT ,ID,ATTR,NAME PATTERN_BYTES lexp two longs: " lexp ---------------------------------------------------------------------------- $$ PAT#,ID,ATTR,NAME NO_OF_PATTERNS wexp the number of patterns in the list: For each pattern: PATTERN_BYTES lexp two longs: " lexp ---------------------------------------------------------------------------- $$ STR ,ID,ATTR,NAME STRING str ---------------------------------------------------------------------------- $$ STR#,ID,ATTR,NAME NO_OF_STRINGS wexp the number of strings in the list: For each string: STRING str ---------------------------------------------------------------------------- $$ WIND,ID,ATTR,NAME TOP wexp bounds rectangle: LEFT wexp BOTTOM wexp RIGHT wexp WINDOW_DEFINITION_ID wexp window type: 0 std doc window or modeless dialog box 1 alert box or modal dialog box 2 plain box 3 plain box with shadow 4 doc window without size box 16 rounded corner window VISIBLE wexp boolean, initial state of window GOAWAY wexp boolean, TRUE means window has a close box REFCON lexp user defined value TITLE str the window's title ---------------------------------------------------------------------------- [[ XXXX,ID,ATTR,NAME user defined resource <DATA/CODE> whatever you want ... ]] don't forget the ender! ---------------------------------------------------------------------------- ************************************************************************** LINKING ************************************************************************** McLink is the linker portion of the McAssembly program. McLink links together .REL files produced by McAssembly and stores the result in a resource file. Depending on the contents of the .REL files, the resulting resource file is either a pure resource file or an executable application. (McAssembly can't link object files which are in the MDS or MPW formats. The reverse is also true. However, McAssembly can generate MPW format object files, and a utility is provided to those who register that will convert McAssembly object files to MDS object files.) The file you specify to McLink is actually a link specification file. It contains the names of the files to be linked and the name of the resulting output file. The specification file has the following format (each filename is on a separate line): input .REL filename 1 input .REL filename 2 ... % input resource filename n % input resource filename n+1 ... * lines starting with an asterisk are comments and are ignored ... * lines starting with an '@' are path specifiers - they specify an HFS * path to use to access all subsequent files @ pathname ... /output filename The input files must be either McAssembly .REL files or resource files. The % character must be the first character of lines containing resource filenames to differentiate them from .REL files. If an input filename doesn't end in .REL and it's not a resource file, McLink adds .REL to the name before it tries to open the file. The output filename must be the last filename in the list and must be preceded by a slash character. Resource files are handled as follows: McLink copies all resources in the resource file to the linked output file. If a resource in the resource file is the same as a resource defined in a .REL file, the resource file copy will replace the .REL file copy in the output file. If a BNDL resource is copied, the output file's bundle bit is set. There are only two aspects of ordering that you must follow: 1.) the first data item in the first file that's linked must be the starting instruction of the program, and 2.) all resources must be linked after all code and/or data. If you attempt to link code after a resource has been linked you get an error message. ************************************************************************** SEGMENTING ************************************************************************** McAssembly lets you divide up your application into segments. To implement segmenting, you have to do two things: 1.) specify what routines in a particular module may be called from other segments, and 2.) specify the partitioning of the code into segments, i.e., what modules are in what segments. Item 1 is accomplished through the use of the JTBL pseudo-op and allows McLink to construct the jump table containing an entry for every cross-segment accessible routine. Item 2 is accomplished by a SEGMENT COMMAND LINE in your link specification file and tells McLink how to break up the code into segments. The JTBL pseudo-op is described earlier and the segment command line description follows. The Segment Command Line is a special command line in the link specification file. It has the following syntax: $ [P] [L] The $ character tells the linker that this line is not the name of a file to be linked but is the start of a new segment. The segment command line writes all modules linked so far to the output file as one segment and groups all subsequent modules (until another segment command line) into a new segment. The P and L parameters specify the attributes of the new code segment. P specifies that the segment is to be "preloaded" and L specifies that the segment is to be "locked." The default for both of these parameters is "not preloaded" and "not locked." (Don't specify a segment command line for the first segment. McLink defaults the attributes for segment number one to "preloaded," "locked," and "purgeable.") Here's an example link specification file for an application that contains four code segments: MAIN $ SEG2A SEG2B $ P SEG3 $ L P SEG4 /MAIN.APPL In this example, MAIN is in segment one, SEG2A and SEG2B in segment two, SEG3 in segment three, and SEG4 in segment four. All segments are purgeable; segments one, three and four are to be preloaded; and segments one and four are locked. The resulting application program is placed in the file MAIN.APPL. ************************************************************************** JOB FILES ************************************************************************** The File menu Run job choice in McAssembly operates on a Job Specification File. A job specification file contains a list of filenames to be assembled and linked to form an output file. By using a job specification file, you eliminate assembling each file separately and invoking the linker to link them. The format of a job specification file is a link specification file whose filenames have no suffixes (.ASM or .REL). In fact, a job specification file can be used as a link specification file, providing it specifies an output file in its last filename line. Here's an example of a job specification file: * This is a comment line * Assemble the file X.ASM if necessary: X * Assemble the file Y.ASM if necessary: Y * Assemble the file Z.ASM if necessary: Z * Put the linked X.REL, Y.REL and Z.REL files into the * output file XYZ: /XYZ To understand what the job control manager does for this file, understand first that a job is run in two phases, an assembly phase and a link phase. The assembly phase assembles the files and the link phase links the resulting .REL files. During the assembly phase, the job control manager ignores any line in the specification file which starts with any of the characters *, $, or / or which is a blank line. These are comment lines and link control lines which have no meaning in assembly. Any other lines are assumed to contain a non-suffixed filename which is a candidate for assembly. For example, the first thing the job control manager does for this job file is to skip the first two lines because they're comment lines. It then operates on the line X. The job control manager looks to see if X.ASM is on the disk. Let's assume for the purposes of this example that X.ASM isn't on the disk. In this case, the job control manager assumes that X.REL exists and that you don't want to reassemble it. So the specification file line containing X is ignored. The next line is examined similarly. Let's assume the converse here - that Y.ASM does exist. The job control manager assembles Y.ASM if either one of the following two conditions is met: 1.) there is no Y.REL file on the disk, or 2.) the existing copy of Y.REL is out-of-date. (It's out-of-date if the modification date of Y.REL is earlier in time than the modification date of Y.ASM.) In either of these two cases, Y.ASM is assembled, creating a new copy of Y.REL. If Y.REL is up-to-date, then the specification line containing Y is skipped and no assembly is performed. Having disposed of the Y file line, the job control manager goes on to the Z file line. A similar analysis goes on as above and Z.ASM is assembled if necessary. Finally, the last line, /XYZ, is examined. The job control manager recognizes this as an output file specification line for the linker, so the linker is invoked. This ends the assembly phase of the job and begins the link phase. In the link phase, the linker links the files using the job specification file as the link specification file. After the link is complete, the job is done and control returns to the top level of McAssembly. If the /XYZ line doesn't exist in the job file, then the job control manager assumes that no link is desired and skips the linker phase of the job. This allows you to use job files for just assemblies. ************************************************************************** FILE SUFFIXES ************************************************************************** McAssembly requires certain suffixes on filenames as follows: (These can be in any combination of upper or lower case.) .asm assembler source files .rel assembler object files .lst assembler listing files .psm assembler packed symbol files .lnk link specification file .job job specification file or link specification file .map linker listing output file .sym binary symbol table output by the linker for use by McBug ************************************************************************** MPW FORMAT ************************************************************************** McAssembly can create object files in the MPW format. The linker can't link them, but you can link them with the MPW linker. MPW object files will have the suffix '.o.' as opposed to the normal '.rel'. There are two special assembler pseudo-ops in MPW mode. You can use them in normal McAssembly mode, but they'll have no effect on the output files. These pseudo-ops and their descriptions are: MAIN Identifies a module as being the main code and data module in the application. This causes two things to happen: 1.) The first instruction in the module will be the first instruction executed when the resulting linked application is executed, and 2.) Any A5SEC data in the module is guaranteed to be located immediately below A5. (This data placement is discussed in more detail below.) (In McAssembly, a "module" is equivalent to a source file. This is different than the MPW definition of a module, which allows any number of modules to be contained in one source file.) SEG ["<segment name>"] Allows you to control the segmentation of your program. Only the last seg statement in a source file is effective. It causes all of the code generated by that file to be placed in a segment named segment name. Code which resides in any particular segment doesn't have to be linked consecutively - the MPW linker figures out what goes where and collects all segment code together regardless of what order the files are linked in. If you don't use a seg statement in a file or use a seg without a segment name then all of the code in the file is placed in a segment named Main by the linker. (Again, this is slightly different than the MPW convention, which allows code in any one source file to be placed into any number of segments.) RESTRICTIONS Just as there are some things you can do in the MPW assembler that you can't do in McAssembly, there are also some McAssembly features that can't be implemented with the MPW object format. Here's what you can't do in MPW mode: 1.) The pseudo-ops A5OFF, FSIGN, and FTYPE are illegal in MPW mode. 2.) None of the resource compiling capabilities can be used. 3.) In McAssembly, you can branch to an externally defined symbol using the Bcc, BSR, and DBcc instructions. You can't do that in MPW. You have to use equivalent JSR and JMP instructions instead. A5 DATA STORAGE The MPW linker has a slightly different perspective of A5 data allocation than MDS had - it's entirely under your control. This means that the linker has no provisions for allowing for the usual $100 bytes of QuickDraw global storage on top of your own A5 data. If your programs rely on this (and they do if they do an InitGraf !-4(A5) when they start up!), then you have to allocate this area specifically yourself. You can do it very simply like this a5sec <your own global variable definitions> ds.b grafSize QuickDraw's space a5end but there are two important restrictions for this to work properly: 1.) The grafSize bytes of A5 storage must be defined in the main module (the source file containing the main pseudo-op.) If it's not in the main module, then the linker will not necessarily place it immediately below A5. 2.) The grafSize bytes of A5 storage must be the last A5 storage item defined in the main module. In other words, if you have several A5SEC's in your main file, then make sure that the grafSize bytes are the last A5SEC item in the file. (This is because McAssembly allocates A5 variables in reverse order of how they appear in the file - the first A5 variable is the lowest in memory, and the last is highest in memory.) (Notice that grafSize, which is defined in the QuickEqu system file, is only $CE bytes, not $100. GrafSize is all that's actually required. I think the $100 was just used for historical reasons as an arbitrarily large enough number.) ************************************************************************** USER-DEFINABLE .MAP FILES ************************************************************************** The McAssembly linker menu contains an option to save link .MAP files in a user-definable format. This is accomplished by the use of a resource containing the user-supplied formatting code. This resource is type UMAP, ID 128. If a .MAP file has been requested, and if the user .MAP file format is selected, then the linker communicates with the UMAP resource code to accomplish the writing of symbol table information to the .MAP file. The default user .MAP file format is an enhanced MDS format, and has been designed to work with Steve Jasik's debugger. It should probably also work with TMON. The source code for the UMAP resource is provided to all registered users so it can easily be modified to support other .MAP formats. ************************************************************************** CONFIGURATION RESOURCES ************************************************************************** The following resources affect McAssembly's operation, and may be changed to whatever you like: STR,128 = The four-character creator string for all text files created by McAssembly. For example, change this to 'QED1' if you use the QUED editor. STR,129 = A string which is sent to the printer before every print job. Change this to whatever your printer likes to see.